1. Início Rápido

Bem-vindo ao guia de início rápido do PixCore! Este tutorial mostrará os passos essenciais para você gerar seu primeiro payload e QR Code Pix de forma simples e direta.

---

Passo 1: Instalação

Primeiro, certifique-se de que a biblioteca esteja instalada. Se ainda não a instalou, utilize o pip:

pip install pixcore

Isso instalará o pixcore e suas dependências necessárias, como qrcode e Pillow.

Passo 2: Importando as Classes Principais

Para começar, você precisará importar duas classes centrais do projeto:

• PixData: Uma classe de dados para armazenar e validar todas as informações da sua cobrança.
• Pix: A classe principal que utiliza os dados do PixData para gerar o payload e o QR Code.

from pixcore import PixData
from pixcore import Pix

Passo 3: Reunindo e Validando os Dados

Agora, crie uma instância de PixData com as informações do recebedor e da transação. A grande vantagem é que esta classe valida os dados automaticamente, garantindo que o nome não é muito longo, que o valor é positivo, etc., prevenindo erros antes mesmo da geração do código.

# Crie um objeto com os dados da cobrança
# Se houver algum dado inválido, um erro (ValueError) será levantado aqui.
try:
    dados_pix = PixData(
        recebedor_nome="EMPRESA MODELO LTDA",
        recebedor_cidade="CIDADE EXEMPLO",
        pix_key="123e4567-e89b-12d3-a456-426655440000", # Use uma chave pix válida aqui
        valor=25.50,
        transacao_id="ID.DA.SUA.TRANSACAO.123"
    )
except ValueError as e:
    print(f"Erro nos dados fornecidos: {e}")

Parâmetros para Geração do Pix (PixData)

A tabela a seguir detalha todos os parâmetros disponíveis ao criar uma instância de PixData.

Parâmetro	Obrigatório?	Descrição	Exemplo de Valor
recebedor_nome	Sim	Nome do recebedor ou da empresa (3 a 25 caracteres).	"EMPRESA MODELO"
recebedor_cidade	Sim	Cidade da transação ou do recebedor (3 a 15 caracteres).	"SAO PAULO"
pix_key	Sim	Chave Pix do recebedor (CPF, CNPJ, E-mail, Telefone ou Chave Aleatória).	"seuemail@dominio.com"
valor	Não	Valor da transação. Se não for definido, o pagador poderá digitar o valor.	10.50
transacao_id	Não	ID único para a transação (alfanumérico, até 25 caracteres). Padrão: ***.	"PEDIDO12345"
ponto_iniciacao_metodo	Não	Define o tipo do QR Code: '11' para dinâmico e '12' para estático.	"12"
receptor_categoria_code	Não	Código da Categoria do Comerciante (MCC). Padrão: "0000".	"5411"
recebedor_cep	Não	CEP do recebedor (deve conter 8 dígitos).	"01001000"
idioma_preferencia	Não	Idioma para dados alternativos do recebedor.	"pt_BR"
recebedor_nome_alt	Não	Nome alternativo do recebedor em outro idioma.	"MODEL COMPANY"
recebedor_cidade_alt	Não	Cidade alternativa do recebedor em outro idioma.	"SAO PAULO"
info_adicional	Não	Campo livre para informações extras (não entra no payload padrão).	"Pagamento ref. NF 123"

Passo 4: Gerando o Payload e o QR Code

Com os dados validados, passe o objeto dados_pix para a classe Pix. A partir daí, você pode gerar o payload (Pix Copia e Cola) ou salvar o QR Code diretamente em um arquivo.

# Instancie a classe principal com os dados validados
gerador_pix = Pix(dados_pix)

# Para obter o payload (Copia e Cola)
payload = gerador_pix.payload()
print("Payload (Copia e Cola):")
print(payload)

# Para gerar e salvar o QR Code em um arquivo
print("\nSalvando QR Code...")
gerador_pix.save_qrcode("meu_primeiro_pix.png")

---

Código Completo (Exemplo Funcional)

Para facilitar, aqui está o script completo que você pode copiar, colar e executar para ver a mágica acontecer.

from pixcore import PixData
from pixcore import Pix

def gerar_cobranca_pix_exemplo():
    """
    Função de exemplo que encapsula todos os passos para gerar um Pix.
    """
    print("Iniciando a geração de uma cobrança Pix...")

    try:
        # 1. Defina e valide os dados da cobrança
        dados_pix = PixData(
            recebedor_nome="EMPRESA MODELO LTDA",
            recebedor_cidade="CIDADE EXEMPLO",
            pix_key="123e4567-e89b-12d3-a456-426655440000", # Chave aleatória (UUID)
            valor=25.50,
            transacao_id="TXID.12345"
        )
        print("Dados validados com sucesso!")

        # 2. Crie a instância principal do gerador
        gerador_pix = Pix(dados_pix)

        # 3. Obtenha o payload (Copia e Cola) e exiba
        payload = gerador_pix.payload()
        print("\n--- Payload (Copia e Cola) Gerado ---")
        print(payload)
        print("------------------------------------")

        # 4. Salve o QR Code em um arquivo
        caminho_arquivo = "pix_exemplo.png"
        gerador_pix.save_qrcode(caminho_arquivo)

        print(f"\nQR Code foi salvo com sucesso em: '{caminho_arquivo}'")

    except ValueError as e:
        # Captura erros de validação da classe PixData
        print(f"\nERRO: Não foi possível gerar o Pix. Motivo: {e}")

if __name__ == "__main__":
    gerar_cobranca_pix_exemplo()

Ao executar este script, ele imprimirá o payload no seu terminal e criará um arquivo de imagem pix_exemplo.png no mesmo diretório.

Pronto! Agora você já sabe o básico para criar cobranças Pix com a biblioteca.